home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / libs / gadutil.lha / GadUtil / docs / 01.GU_PreliminaryDocs next >
Text File  |  1995-06-26  |  17KB  |  432 lines
  1.                                 GadUtil tags
  2.                                ~~~~~~~~~~~~~~
  3. Tags to use for the yet undocumented function GU_LayoutGadgetsA().
  4.  
  5. Tags to use in the tag lists for each gadget to create. Note that
  6. you do not have to specify any tags that not change from gadget to
  7. gadget.
  8.  
  9. GU_GadgetKind (ULONG)
  10.     Can be any of the standard GadTools gadget kinds, or one of the
  11.     extensions provided by GadUtil. Currently extended types are:
  12.  
  13.     IMAGE_KIND
  14.         A gadget that uses an Intuition Image structure for its
  15.         contents. Selected and unselected states can use different
  16.         images. The images are centered automatically.
  17.  
  18.         Extra tags for IMAGE_KIND:
  19.  
  20.             GUIM_Image (struct Image *)
  21.                 Image for the gadget in its unselected state. This is
  22.                 the only required (extra) tag for IMAGE_KIND gadgets.
  23.  
  24.             GUIM_SelectImg (struct Image *)
  25.                 Image for the gadget in its selected state. If this tag
  26.                 is omitted, the selected image will be the same as the
  27.                 unselected, and only the border and the background color
  28.                 will change (depending on the GUIM_BOOPSILook tag).
  29.  
  30.             GUIM_ReadOnly (BOOL)
  31.                 TRUE to create a read-only image gadget.
  32.  
  33.             GUIM_BOOPSILook (BOOL)
  34.                 This tag will allow the programmer to select how the
  35.                 secondary image should be shown, if only one image is
  36.                 used for the gadget. Defaults to TRUE, which means that
  37.                 the background color will change when the user selects
  38.                 the gadget.
  39.  
  40.     DRAWER_KIND
  41.         A "select drawer" image button. This can be used to select
  42.         a path, but is often used to select files.
  43.  
  44.     FILE_KIND
  45.         A "select file" image button. This can be used to allow the
  46.         user to select a file. Most programs uses the DRAWER_KIND
  47.         for both file and path selection.
  48.  
  49.     BEVELBOX_KIND
  50.         A GadTools bevelbox. Use this to avoid the use of absolute
  51.         sizing of bevelboxes. All bevel box kinds from OS3.0 is
  52.         supported, even if the computer only has OS2.0.
  53.  
  54.         Extra tags for BEVELBOX_KIND:
  55.  
  56.             GUBB_Recessed (BOOL)
  57.                 Create a recessed ("pushed in") bevel box. Differs from
  58.                 the GadTools tag GTBB_Recessed, in that it works with
  59.                 both TRUE and FALSE as parameter. GadTools creates a
  60.                 recessed box independent from the given value.
  61.  
  62.                 Defaults to FALSE.
  63.  
  64.             GUBB_FrameType (ULONG)
  65.                 Determines what kind of box this function renders. The
  66.                 current available alternatives are:
  67.  
  68.                     BFT_BUTTON - Generates a box like what is used around
  69.                                  a GadTools BUTTON_KIND gadget.
  70.  
  71.                     BFT_RIDGE - Generates a box like what is used around
  72.                                 a GadTools STRING_KIND gadget.
  73.  
  74.                     BFT_DROPBOX - Generates a box suitable for a standard
  75.                                   icon drop box imagery.
  76.  
  77.                     BFT_HORIZBAR - Generates a horizontal shadowed line.
  78.                                    Can also be used to draw a normal line,
  79.                                    using 1 for the line's height.
  80.  
  81.                     BFT_VERTBAR - Generates a vertical shadowed line. Can
  82.                                   also be used to draw a normal line, using
  83.                                   1 for the line's width.
  84.  
  85.                 Defaults to BFT_BUTTON.
  86.  
  87.             GUBB_TextColor (ULONG)
  88.                 Selects which color to print the title text in. Only useful
  89.                 for a bevelbox with a title. Defaults to the color of the
  90.                 TEXTPEN.
  91.  
  92.             GUBB_TextPen (ULONG)
  93.                 Selects which pen to print the title text in. Only
  94.                 useful for a bevelbox with a title. Defaults to TEXTPEN.
  95.                 This tag overrides the GUBB_TextColor tag.
  96.  
  97.             GUBB_Flags (ULONG)
  98.                 Currently, only text placement flags are defined. These are:
  99.  
  100.                 Y-pos flags
  101.                 ~~~~~~~~~~~
  102.                     BB_TEXT_ABOVE - Places the bevel box text above the upper
  103.                                     border of the box           ___Example___
  104.  
  105.                     BB_TEXT_IN    - Places the bevel box text at the upper
  106.                                     border of the box           ---Example---
  107.  
  108.                     BB_TEXT_BELOW - Places the bevel box text below the upper
  109.                                     border of the box           ___       ___
  110.                                                                    Example
  111.                 X-pos flags
  112.                 ~~~~~~~~~~~
  113.                     BB_TEXT_CENTER - Places the bevel box text in the middle
  114.                                      of the upper border        ---Example---
  115.  
  116.                     BB_TEXT_LEFT   - Places the bevel box text 8 pixels from
  117.                                      the left edge of the box   -Example-----
  118.  
  119.                     BB_TEXT_RIGHT  - Places the bevel box text 8 pixels from
  120.                                      the right edge of the box  -----Example-
  121.  
  122.                 Default if BB_TEXT_ABOVE!BB_TEXT_CENTER. Combine the x and y
  123.                 position flags by OR:ing them together. Don't combine two X
  124.                 or two Y flags together.
  125.                 
  126.     Changed tags, and additions to GadTools:
  127.  
  128.     LISTVIEW_KIND:
  129.  
  130.         GTLV_ShowSelected (UWORD id)
  131.  
  132.             This tag was changed, so that you don't have to create the
  133.             string gadget before all other gadgets. The difference from
  134.             this tag in GadTools, is that we now have to give the ID of
  135.             the string gadget to use to show the selected item.
  136.  
  137.             An example of a valid (and probably most useful) gadget to
  138.             use for GTLV_ShowSelected:
  139.  
  140.             ShowSelGad:
  141.                 dc.l    GU_GadgetKind,  STRING_KIND,    GU_AutoHeight,  4
  142.                 dc.l    GU_DupeWidth,   GAD_LISTVIEW,   GU_GadgetText,  NULL
  143.                 dc.l    TAG_DONE
  144.  
  145.             This gadget MUST be before the LISTVIEW gadget in the LayoutGadget
  146.             array.
  147.  
  148.             Special:
  149.  
  150.             ti_Data = -1    Creates a read-only gadget below the listview,
  151.                             same as for GTLV_ShowSelected, 0  for GadTools.
  152.  
  153.             ti_Data =  x    Gadget ID for the gadget that the selected item
  154.                             should be displayed in. Same as GadTools reaction
  155.                             on a gadget pointer in ti_Data.
  156.  
  157.             This gadget's ti_Data field will be changed during the creation
  158.             of the gadget, but will be changed back before GU_LayoutGadgets
  159.             returns.
  160.  
  161.     MX_KIND:
  162.  
  163.         The gng_GadgetText field in the NewGadget structure can be used even
  164.         with MX_KIND gadgets. This should have been included in GadTools.
  165.         The gadget text will always be placed ABOVE the gadget, on the same
  166.         side as the other texts for the gadget. Positions are checked against
  167.         WBPattern & SerialPrefs to get them "right". The GU_GadgetText and
  168.         GU_LocaleText tags are used to access this field.
  169.  
  170. Tags for all gadget kinds:
  171.  
  172. Gadget width control:
  173.  
  174.     GU_Width (UWORD wid)
  175.         Absolute width of the gadget. Not recommended to use for other
  176.         gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  177.  
  178.     GU_DupeWidth (UWORD id)
  179.         Duplicate the width of another gadget.
  180.  
  181.     GU_AutoWidth (WORD add)
  182.         Width = length of text label + ti_Data. This tag doesn't work
  183.         as it should with CYCLE_KIND and MX_KIND gadgets. Will be fixed
  184.         later. Use GU_Columns for those kinds until this is fixed.
  185.  
  186.     GU_Columns (UWORD numcols)
  187.         Set the gadget width so that approximately ti_Data columns of
  188.         text will fit.
  189.  
  190.     GU_AddWidth (WORD add)
  191.         Add ti_Data to the total width calculation.
  192.  
  193.     GU_MinWidth (UWORD wid)
  194.         Make the gadget at least ti_Data pixels wide.
  195.  
  196.     GU_MaxWidth (UWORD wid)
  197.         Make the gadget at most ti_Data pixels wide.
  198.  
  199.     GU_AddWidChar (WORD chars)
  200.         Add the length of ti_Data characters to the total width calculation.
  201.  
  202. Gadget height control:
  203.  
  204.     GU_Height (UWORD hei)
  205.         Absolute height of the gadget. Not recommended to use for other
  206.         gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  207.         
  208.     GU_DupeHeight (UWORD id)
  209.         Duplicate the height of another gadget.
  210.  
  211.     GU_AutoHeight (WORD add)
  212.         Height = height of the gadget's font + ti_Data. This tag doesn't
  213.         work as it should with MX_KIND gadgets. Will be fixed later.
  214.         Use GU_HeightFactor or GU_Height for MX_KIND until this is fixed.
  215.  
  216.     GU_HeightFactor (UWORD numlines)
  217.         Set the gadget height to approximately ti_Data lines.
  218.  
  219.     GU_AddHeight (WORD add)
  220.         Add ti_Data to the total height calculation.
  221.  
  222.     GU_MinHeight (UWORD wid)
  223.         Make the gadget at least ti_Data pixels high.
  224.  
  225.     GU_MaxHeight (UWORD wid)
  226.         Make the gadget at most ti_Data pixels high.
  227.  
  228.     GU_AddHeiLines (WORD numlines)
  229.         Add the height of ti_Data/2 lines to the final height calculation.
  230.         The numlines argument is given in units of 1/2 lines to get
  231.         better resolution (ti_Data of 4 means that the height of 2
  232.         lines should be added).
  233.  
  234. Gadget top edge control:
  235.  
  236.     GU_Top, GU_TopRel and GU_AlignTop locks the top edge of the gadget, and
  237.     allows any bottom edge control tag to adjust the height, so that both
  238.     top and bottom edges will be correct.
  239.  
  240.     GU_Top (UWORD ypos)
  241.         Absolute top edge of the gadget. Not recommended to use for other
  242.         gadgets than the top-most gadgets.
  243.  
  244.     GU_TopRel (UWORD id)
  245.         Make the top edge relative to another gadgets bottom edge. This
  246.         gadget will be placed BELOW the given gadget.
  247.  
  248.     GU_AddTop (WORD add)
  249.         Add ti_Data to the final top edge calculation.
  250.  
  251.     GU_AlignTop (UWORD id)
  252.         Align the top edge of the gadget with another gadgets top edge.
  253.  
  254.     GU_AdjustTop (WORD add)
  255.         Add the height of the text font + ti_Data to the top edge.
  256.  
  257.     GU_AddTopLines (WORD numlines)
  258.         Add the height of ti_Data/2 lines to the final top edge. The
  259.         numlines argument is given in units of 1/2 lines to get better
  260.         resolution (ti_Data of 4 means that the height of 2 lines
  261.         should be added).
  262.  
  263. Gadget bottom edge control:
  264.  
  265.     GU_Bottom, GU_BottomRel and GU_AlignBottom locks the bottom edge of the
  266.     gadget, and allows any top edge control tag to adjust the height, so that
  267.     both top and bottom edges will be correct.
  268.  
  269.     GU_Bottom (UWORD ypos)
  270.         Absolute bottom edge of the gadget. Not recommended to use for other
  271.         gadgets than the bottom-most gadgets. Should not be necessary to use
  272.         at all.
  273.  
  274.     GU_BottomRel (UWORD id)
  275.         Make the bottom edge relative to another gadgets top edge. This
  276.         gadget will be placed ABOVE the given gadget.
  277.  
  278.     GU_AddBottom (WORD add)
  279.         Add ti_Data to the final bottom edge calculation.
  280.  
  281.     GU_AlignBottom (UWORD id)
  282.         Align the bottom edge of the gadget with another gadgets bottom edge.
  283.  
  284.     GU_AdjustBottom (WORD add)
  285.         Subtract the height of the gadget's font + ti_Data from the top edge.
  286.         This will move the gadget UPWARDS (ti_Data + font height) pixels.
  287.  
  288. Gadget left edge control:
  289.  
  290.     GU_Left, GU_LeftRel and GU_AlignLeft locks the left edge of the gadget,
  291.     and allows any right edge control tag to adjust the width, so that both
  292.     left and right edges will be correct.
  293.  
  294.     GU_Left (UWORD xpos)
  295.         Absoulute left edge of the gadget. Not recommended to use for other
  296.         gadgets than the left-most gadgets.
  297.  
  298.     GU_LeftRel (UWORD id)
  299.         Make the left edge relative to another gadgets right edge. This
  300.         gadget will be placed TO THE RIGHT of the given gadget.
  301.  
  302.     GU_AddLeft (WORD add)
  303.         Add ti_Data to the final left edge calculation.
  304.  
  305.     GU_AlignLeft (UWORD id)
  306.         Align the left edge of the gadget with another gadgets left edge.
  307.  
  308.     GU_AdjustLeft (WORD add)
  309.         Add the width of the gadget label + ti_Data to the left edge.
  310.  
  311.     GU_AddLeftChar (WORD chars)
  312.         Add the length of ti_Data characters to the left edge.
  313.  
  314. Gadget right edge control:
  315.  
  316.     GU_Right, GU_RightRel and GU_AlignRight locks the right edge of the
  317.     gadget, and allows any left edge control tag to adjust the width, so
  318.     that both left and right edges will be correct.
  319.  
  320.     GU_Right (UWORD xpos)
  321.         Absoulute right edge of the gadget. Not recommended to use for other
  322.         gadgets than the right-most gadgets. Should not be necessary to use
  323.         at all.
  324.  
  325.     GU_RightRel (UWORD id)
  326.         Make the right edge relative to another gadgets left edge. This
  327.         gadget will be placed TO THE LEFT of the given gadget.
  328.  
  329.     GU_AddRight (WORD add)
  330.         Add ti_Data to the final right edge calculation.
  331.  
  332.     GU_AlignRight (UWORD id)
  333.         Align the right edge of the gadget with another gadgets right edge.
  334.  
  335.     GU_AdjustRight (WORD add)
  336.         Add the width of the gadget label + ti_Data to the left edge.
  337.  
  338. Other tags:
  339.  
  340.     GU_ToggleSelect (BOOL)
  341.         Create a toggle select gadget. Works with BUTTON_KIND and IMAGE_KIND
  342.         gadgets.
  343.  
  344.     GU_Selected (BOOL)
  345.         Set the initial value of a toggle select gadget.
  346.  
  347.     GU_Hotkey (CHAR)
  348.         Hotkey that should simulate a press (release) of a gadget.
  349.  
  350.     GU_HotkeyCase (BOOL)
  351.         Make the hotkey case-sensitive. Default is not case sensitive.
  352.  
  353.     GU_LabelHotkey (BOOL)
  354.         Get the hotkey directly from the gadget's label. The hotkey can
  355.         be case-sensitive, but not for CYCLE, LISTVIEW and MX gadgets.
  356.  
  357.     GU_RawKey (BYTE)
  358.         Use a rawkey as a gadget hotkey. May not be case-sensitive.
  359.         
  360. Tags that gives access to other fields in the NewGadget structure:
  361.  
  362.     GU_GadgetText (UBYTE *)
  363.         A pointer to the gadget's label. Will be copied directly into the
  364.         gng_GadgetText field of the NewGadget structure.
  365.  
  366.     GU_TextAttr (struct TextAttr *)
  367.         A pointer to an initialized TextAttr structure (to select the font).
  368.         Will be copied directly into the gng_TextAttr field of the NewGadget
  369.         structure.
  370.  
  371.     GU_Flags (ULONG)
  372.         Gadget flags. Currently available flags are as for GadTools, but
  373.         here is a short list of them:
  374.  
  375.         PLACETEXT_LEFT - Place the gadget label right aligned on the left
  376.                          side of the gadget.
  377.  
  378.         PLACETEXT_RIGHT - Place the gadget label left aligned on the right
  379.                           side of the gadget.
  380.  
  381.         PLACETEXT_ABOVE - Place the gadget label centered above the gadget.
  382.  
  383.         PLACETEXT_BELOW - Place the gadget label centered below the gadget.
  384.  
  385.         PLACETEXT_IN - Place the gadget label centered inside the gadget.
  386.  
  387.         NG_HIGHLABEL - Highlight the label (render it using SHINEPEN).
  388.  
  389.     GU_UserData (APTR)
  390.         Storage for your own data. Will probably be removed, since GadUtil
  391.         uses this filed for an internal structure (with some external
  392.         available fields).
  393.  
  394.     GU_LocaleText (ULONG stringid)
  395.         Get gadget label from a catalog. This allows easy localization of
  396.         all new programs.
  397.  
  398. Tags that should be passed directly to GU_LayoutGadgetsA():
  399.  
  400.     GU_RightExtreme (ULONG *)
  401.         A pointer to a longword that is used to store the rightmost point
  402.         that a gadget will exist in.
  403.  
  404.     GU_LowerExtreme (ULONG *)
  405.         A pointer to a longword that is used to store the lowermost point
  406.         that a gadget woll exist in.
  407.  
  408.     GU_Catalog (struct Catalog *)
  409.         A pointer to the programs translation catalog. NULL indicates that
  410.         the program should use the internal strings. You must open the
  411.         catalog by yourself (use GU_OpenCatalog() or locale/OpenCatalog).
  412.         The GU_AppStrings tag MUST be used together with this tag.
  413.  
  414.     GU_DefTextAttr (struct TextAttr *)
  415.         Specifies the default font to use with all gadgets. Can be over-
  416.         ridden with GU_TextAttr tag for each gadget.
  417.  
  418.     GU_AppStrings (struct AppString *)
  419.         A pointer to an array of AppString structures. These strutures
  420.         contains the programs internal strings.
  421.         This tag must be used together with the GU_Catalog tag.
  422.  
  423.     GU_BorderLeft (ULONG)
  424.         Size of the window's left border.
  425.  
  426.     GU_BorderTop (ULONG)
  427.         Size of the window's top border.
  428.  
  429.     GU_NoCreate (BOOL)
  430.         Don't create any gadgets. Useful to determine if the window will
  431.         fit on the screen etc.
  432.